---
title: '@roots/bud-postcss'
description: 'postcss support for bud.js projects'
sidebar_label: '@roots/bud-postcss'
---

This extension adds [PostCSS](https://postcss.org) support.

## Installation

```sh npm2yarn
npm install @roots/bud-postcss --save-dev
```

## Usage

By default, **@roots/bud-postcss** includes the following plugins, registered with PostCSS in this order:

| Order | Plugin                                                      |
| ----- | ----------------------------------------------------------- |
| 1     | [postcss-import](https://github.com/postcss/postcss-import) |
| 2     | [postcss-nested](https://github.com/postcss/postcss-nested) |
| 3     | [postcss-preset-env](https://preset-env.cssdb.org/)         |

If this works for you, great! No need to keep reading.

Should you need something more specialized, you can configure PostCSS in your bud config file or a
standard PostCSS config file.

Note that by using a PostCSS config file you will be overriding the bud.js options API.

## Overriding PostCSS options directly

You can set the PostCSS options directly using `bud.postcss.setPostCssOptions`.

It's best to use this method only if you are comfortable with PostCSS and know what you are doing.

```ts title=bud.config.ts
bud.postcss.setPostCssOptions({
  parser: `sugarss`,
  plugins: [`postcss-import`, `postcss-nested`, `postcss-preset-env`],
})
```

Doing it this way is to-the-point but you are fully overriding the default settings.
Other bud.js extensions related to PostCSS will likely not work.

## Adding a plugin

Adding a plugin with the API is a two step process:

1. [Register the plugin](#step-1-registration)
2. [Add it to the plugin order](#step-2-add-the-plugin)

Let's look at how this is done using `tailwindcss` as an example.

```ts title=bud.config.ts
bud.postcss
  /** Register the tailwindcss/nesting plugin */
  .setPlugin(`tailwindcss/nesting`)
  /** Register the tailwindcss plugin and options */
  .setPlugin(`tailwindcss`)
  /** Specify which registered plugins you want to use, in the order they should be added */
  .use([`import`, `tailwindcss/nesting`, `tailwindcss`, `env`])
```

### Step 1. Registration

```ts title=bud.config.ts
bud.postcss.setPlugin(`example-postcss-plugin`)
```

If you want to be specific about how to resolve a plugin, you can pass a second parameter.

```ts title=bud.config.ts
bud.postcss.setPlugin(
  `example-postcss-plugin`,
  bud.path(`@modules/example-postcss-plugin/lib/index.js`),
)
```

If you want to pass along options with the plugin, you can do so by passing an array.

```ts title=bud.config.ts
bud.postcss.setPlugin(`example-postcss-plugin`, [
  `example-postcss-plugin`,
  {stage: 1},
])
```

### Step 2. Add the plugin

```ts title=bud.config.ts
bud.postcss.use([
  `postcss-import`,
  `postcss-nesting`,
  `example-postcss-plugin`, // our new plugin
  'postcss-preset-env',
])
```

You can also use a callback:

```ts title=bud.config.ts
bud.postcss.use(plugins => [...plugins, 'example-postcss-plugin'])
```

## Override plugin options

You can modify options for a plugin using **bud.postcss.setPluginOptions**.

The first parameter is the plugin key and the second is the options object.

```ts title=bud.config.ts
bud.postcss.setPluginOptions('example-postcss-plugin', {optimize: false})
```

## Override plugin path

You can modify the path for a PostCSS plugin using **bud.postcss.setPluginPath**.

The first parameter is the plugin key and the second is the new path to assign.

```ts title=bud.config.ts
bud.postcss.setPluginPath(
  'example-postcss-plugin',
  bud.path('./lib/my-plugin.js'),
)
```

## Remove a plugin

You may remove a plugin by calling **bud.postcss.unsetPlugin** with the plugin key.

```ts title=bud.config.ts
bud.postcss.unsetPlugin(`import`)
```

## Additional options

| Option      | Type      | Default     |
| ----------- | --------- | ----------- |
| `parser`    | `string`  | `undefined` |
| `sourceMap` | `boolean` | `true`      |
| `syntax`    | `string`  | `undefined` |

Each option has an associated getter and setter.

### bud.postcss.parser

The parser option is used to specify the parser to use for the PostCSS processor.

```ts
bud.postcss.setParser(`postcss-sass`)
```

### bud.postcss.sourceMap

The sourceMap option is used to specify whether or not to generate a source map.

```ts
bud.postcss.setSourceMap(false)
```

### bud.postcss.syntax

The syntax option is used to specify the syntax to use for the PostCSS processor.

```ts
bud.postcss.setSyntax(`sugarss`)
```
